<h1>Installation Instructions</h1>


<a id="getsoftware"></a><h2>Getting the Software</h2>

Please follow the instructions in the <a href="https://github.com/libMesh/libmesh">README file</a> to download/clone and install libMesh.
Note that the installation instructions may change over time, but the README file should always contain the most up-to-date information.

<a id="compilers"></a><h2>Compilers</h2>

<code>libMesh</code> requires a C++17 compliant compiler.
<br>

<a id="test"></a><h2>Testing the Library</h2>

<code>libMesh</code> Continuous Integration testing (example codes and unit tests) is
automatically performed on all PRs for members of the libMesh Project's "Associates" Team.
If you submit a PR, you will be invited to join this Team so that your PRs are tested automatically.
<br>

<h3>Running the Examples</h3>
<code>libMesh</code> includes a number of examples in the <code>examples</code>
directory. From the top-level directory you can build and run the example programs
by typing
<div class="fragment">
<pre>make check</pre>
</div>

<br>
Note that many of the the example programs create output in the <code>ExodusII</code> format,
since you can <a href="http://www.paraview.org">download Paraview</a>
for free, and it is a highly capable postprocessing tool. It is a simple matter to change the source
in the example to write a different formats, however.


<h3>Unit Tests</h3>
The repository contains a top-level <code>tests</code> directory
with a series of unit tests that can be used to validate a <code>libMesh</code>
installation.  These unit tests require <a href="https://freedesktop.org/wiki/Software/cppunit/">CPPUnit</a>
to run properly.  To run the unit test suite, from the <i>build</i> directory, simply do

<div class="fragment">
  <pre>make -C tests check </pre>
</div>

<a id="external"></a><h2>External Software</h2>

<code>libMesh</code> has many features which are enabled via
integration with <a href="externalsoftware.html">various third-party
libraries</a>, a few of which are redistributed in our contrib
directory, others of which may be separately installed on your system.
The libMesh configure script attempts to autodetect these libraries
when possible.  Some of the supported libraries have occasionally
changing (or even frequently changing) APIs.  We attempt to provide a
range of backwards compatibility for old versions of third-party APIs.

<a id="link"></a><h2>Linking With Your Application</h2>

Since <code>libMesh</code> can be configured with many additional packages we recommend
including the <code>Make.common</code> file created in the top-level directory in the
<code>Makefile</code> of any application you want to use with the library. This will
properly set the <code>libmesh_INCLUDE</code> and <code>libmesh_LIBS</code> variables, which you can
append to with your own stuff.

<br>
For testing simple programs you may want to use the <code>libmesh-config</code> script
included in the <code>contrib/bin</code> directory instead of creating a <code>Makefile</code>.
This script may be used to determine the relevant compilation and linking flags
used by <code>libMesh</code>. For example, you could build the application <code>foo</code> from
<code>foo.C</code> like this:
<div class="fragment">
<pre> `libmesh-config --cxx` -o foo foo.C `libmesh-config --cxxflags --include --ldflags --libs`</pre>
</div>


<br>


<a id="windows"></a><h2>Building on Windows</h2>

<p>
The <code>libMesh</code> library can be built on Microsoft Windows using the
<a href="http://www.msys2.org/">msys2</a> software distribution and the
<a href="http://mingw-w64.org/">mingw-w64</a> compiler. There are, however, a few
specifics that need to be taken into account.
</p>

<p>
After installing msys2 you need to install the mingw-w64 C++ compiler. To check that
the installation was successful, you can run
</p>
<div class="fragment">
<pre>g++ --version</pre>
</div>
<p>
in the msys2 shell.
</p>

<p>
When you checkout the current version of <code>libMesh</code> using Git on Windows
symlinks might not work. You can check whether your symlinks are set correctly by
inspecting whether the README file points to the README.md file. If this is not the
case, you should run the <code>contrib/bin/fix_windows_symlinks.sh</code> from within
the git repository using the msys2 shell. This script removes all symlinks and copies
the symlink targets to the corresponding places.
</p>

<p>
Not all <em>optional</em>
dependencies are available on Windows.
It is known that the following packages do not compile on Windows.
</p>
<ul>
    <li>fparser, Function Parser for C++</li>
    <li>METIS, Serial Graph Partitioning and Fill-reducing Matrix Ordering</li>
</ul>
<p>
Hence, these libraries need to be deactivated, using the corresponding flags.
For example by configuring <code>libMesh</code> with the following command.
</p>
<div class="fragment">
<pre>./configure --prefix=c:/libmesh \
    --disable-metis \
    --with-fparser=none</pre>
</div>
<p>
Then, the library can be built and installed using:
</p>
<div class="fragment">
<pre>make
make install</pre>
</div>
